Skip to content

refactor(dash-tui): build the Esc menu from one list of items - #913

Merged
jussielo-amd merged 5 commits into
mainfrom
refactor-dash-tui-single-menu-item-list
Nov 5, 2026
Merged

jussielo-amd merged 5 commits into
mainfrom
refactor-dash-tui-single-menu-item-list

Conversation

@jussielo-amd

Copy link
Copy Markdown
Collaborator

Summary

The dashboard's Esc menu had its item count written down in three separate places, kept in step only by convention: MENU_ITEMS in app/types.rs (the wrap bound of the up/down keys), MENU_ITEM_COUNT in ui/menu.rs (how tall the box must be before the menu is drawn at all), and a local ["Options", "Help", "Quit"] array inside draw_menu (the rows actually painted). The activation match in app/actions.rs restated the order a fourth time as bare indexes (0, 1, anything else). Adding or removing a row meant editing all of them, and a missed copy would have shown as a row that can be selected but is not drawn, a row that is drawn but cannot be reached, or a row clipped off the bottom of a short box, with no compile error and no failing test.

This change makes MENU_ITEMS the one list. It is now a slice of a new MenuItem enum (Options, Help, Quit) that carries each row's label. The wrap bound is MENU_ITEMS.len(), MENU_ITEM_COUNT is computed from it, draw_menu iterates it and prints item.label(), and the activation match is over MenuItem, so the compiler now requires an arm for every row. This is part of the Phase 8.4-H follow-up work (behaviour-neutral consolidations); it is one bullet of that item and does not close it.

Which copy wins and why

There was nothing to arbitrate: the three copies agreed (three rows: Options, Help, Quit), so the surviving behaviour is simply the current one. The list lives in app/types.rs rather than in ui/menu.rs because that file already owns the command-palette and options-tab lists (PALETTE_DESTS, OPTIONS_TABS) that the key handling and the renderer both read, and docs/architecture.md already says ui/menu.rs depends on app/types.rs and not the reverse. Keeping the data there adds no module cycle. The existing shape (a const next to its siblings, read by both sides) is kept rather than introducing a new mechanism.

What changed

  • app/types.rs: MENU_ITEMS: usize = 3 becomes MENU_ITEMS: &[MenuItem], with the new MenuItem enum and MenuItem::label.
  • app/mod.rs: re-exports MenuItem beside MENU_ITEMS.
  • app/actions.rs: MenuMove wraps over MENU_ITEMS.len(); MenuActivate matches MENU_ITEMS.get(menu_sel) on Some(MenuItem::Options), Some(MenuItem::Help) and Some(MenuItem::Quit) | None. The None case keeps the old _ arm's behaviour for a selection past the last row (it still quits). Nothing sets menu_sel out of range today (OpenMenu resets it and MenuMove wraps it), so this only preserves the old fallback exactly.
  • ui/menu.rs: MENU_ITEM_COUNT is MENU_ITEMS.len() as u16; draw_menu loops over MENU_ITEMS; the local label array is gone.
  • docs/architecture.md: the app/types.rs entry said the Esc menu's own item count was a separate constant in ui/menu.rs; it now says the rows, labels, wrap bound and reserved height all come from the one list.
  • tests/e2e-cucumber/tests/e2e/dash_steps.rs: a doc comment on a step definition named the label array in ui/menu.rs; it now points at MENU_ITEMS. Comment only, no scenario or step logic touched.

The leaf-name test list against origin/main differs only by the six added tests below.

Verification

Commit order is characterisation first, then the consolidation. The first commit adds tests only and they pass on the unchanged code:

  • esc_menu_draws_options_help_quit_in_order_with_only_the_selected_row_marked: for each selection, the exact three rows below the logo, in order, with ▸ only on the selected row, on consecutive screen rows.
  • esc_menu_item_rows_sit_at_a_fixed_column_with_focus_styling: the exact cells (cursor column, label column, accent colour and bold on the selected label, plain foreground and not bold on the others).
  • esc_menu_is_drawn_only_when_the_box_is_tall_enough_for_every_item: on a 120-column screen, height 19 draws an empty frame (no logo, no items) and height 20 draws the logo and all three labels.
  • esc_menu_selection_wraps_over_its_three_rows_and_each_row_runs_its_own_action: opens on row 0, up wraps to row 2, down wraps to row 0, a full lap visits 1, 2, 0; row 0 opens Options on tab 0, row 1 opens the global help, row 2 quits.
  • esc_menu_draws_the_rows_of_the_list_the_selection_walks: the drawn rows equal MENU_ITEMS label for label (in the first commit this compared the number of drawn rows with the wrap bound).
  • Added with the consolidation: esc_menu_selection_past_the_last_row_still_quits. It passes on the old code too, by reading the old _ arm; I did not run it against the old code.

Mutation proof. Against the first commit (the three copies still separate), each divergence turns tests red:

  • add a fourth label to draw_menu's array only: the ordered-rows test, the drawn-rows-equal-the-wrap-bound test and the height test fail;
  • set MENU_ITEMS to 4 only: the wrap test and the drawn-rows-equal-the-wrap-bound test fail;
  • set MENU_ITEM_COUNT to 4 only: the height test and the existing esc_menu_requires_room_for_all_items fail.

Against the final code: dropping Help from MENU_ITEMS fails six tests (the pins, the height tests and menu_navigation_and_activation); adding a duplicate fourth entry fails the ordered-rows pin, both height tests and the wrap test while esc_menu_draws_the_rows_of_the_list_the_selection_walks stays green, which is the point of the change (the drawn rows and the key handling can no longer disagree, so only the deliberate literal pins report that the menu changed); replacing the None arm with a no-op fails esc_menu_selection_past_the_last_row_still_quits. Every mutation was restored with a targeted reverse edit.

Ran: cargo fmt --all --check; cargo clippy -p rocm-dash-tui --all-targets -- -D warnings; cargo test -p rocm-dash-tui --no-fail-fast (1002 unit tests plus the crate's integration tests, all passing); cargo xtask manifest --check; cargo xtask check-crate-edges; cargo xtask lychee and the lychee commit hook; the leaf-name test-list diff against a clean origin/main worktree; the leak scan over git diff origin/main...HEAD.

Not run: the Windows-target clippy cross-check (the toolchain cannot build aws-lc-sys for x86_64-pc-windows-msvc here; none of the touched code is platform-gated); cargo xtask e2e, scripts/smoke_local.py and the full workspace gate, which CI carries.

User-visible behaviour

None. Same items, same order, same labels, same keys and the same drawn screen. No scenario is added because nothing a user can observe changes. The scenarios that already cover the menu and keep covering it are @id:dash-chat-idle-escape-opens-menu (dash-14: Escape opens the menu from the Chat tab and a second Escape closes it) and @id:dash-esc-menu-quit-row-confirms-when-serving (dash-34: navigating to the Quit row and activating it asks the quit confirmation). Both are tagged only @requires-os:linux, so no GPU or nightly gate applies; they run on the Linux e2e lane in CI. I did not run them locally.

Notes for reviewers

Read the two commits in order: the first only adds tests (green on the unchanged code), the second changes the production code and nothing in the tests except the one comparison that moved from a count to labels. The new MenuItem enum does not make a variant missing from MENU_ITEMS a compile error (stable Rust cannot check that without a derive macro the crate does not depend on); the doc comment on MENU_ITEMS says so, as ScrollTarget::ALL does for its list. The only other restatement of the order is the MenuActivate match, which the compiler now checks for completeness.

Open PRs: I checked the open list for PRs touching the menu code and found none that edit ui/menu.rs, MENU_ITEMS or the activation arm. Several open PRs touch docs/architecture.md, and #721 includes the ui/menu.rs bullet as unchanged context, so a rebase may need a manual look at that file but the lines I changed (the app/types.rs bullet) are not edited there. #868 edits tests/e2e-cucumber/tests/e2e/dash_steps.rs in other step definitions, away from the doc comment changed here.

The Esc menu's item list is stated in three places that nothing but
convention keeps in step: the wrap bound the key handling uses, the
height the draw guard reserves, and the labels the draw routine paints.
Pin what the menu does today before those are collapsed into one list:

- the three rows drawn, in order, with the cursor only on the selected
  row, their column and their focus styling;
- the smallest screen on which the menu is drawn at all (every item has
  to fit);
- that the number of drawn rows equals the wrap bound;
- that selection wraps in both directions over three rows and that each
  row runs its own action.

No production code changes.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The Esc menu's item count was stated three times: `MENU_ITEMS` (the wrap
bound of the key handling), `MENU_ITEM_COUNT` (the height the draw guard
reserves) and the local label array in `draw_menu`, and the activation
match restated the order a fourth time as bare indexes. Nothing but a
doc comment kept them in step.

`MENU_ITEMS` is now the one list, a slice of a new `MenuItem` enum that
carries each row's label. The wrap bound is its length, `MENU_ITEM_COUNT`
is derived from it, `draw_menu` iterates it, and the activation match is
over `MenuItem`, so the compiler requires an arm for every row.

No behaviour change: same three rows in the same order with the same
labels, same wrap, same drawn output, and a selection past the last row
still quits as the old `_` arm did (now pinned by a test).

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the refactor consolidating the dashboard’s Esc menu around a shared typed list.

No open issues 🎉

What changed in this PR

Consolidates the dashboard’s Esc menu around one typed MENU_ITEMS list, keeping rendering, navigation, sizing, and activation aligned without changing user-visible behavior.

Changes:

  • Introduces MenuItem with shared labels and replaces duplicated counts and index-based activation.
  • Adds six regression tests covering menu appearance, sizing, navigation, activation, and the existing out-of-range fallback.
  • Updates architecture documentation and an e2e step’s doc comment to describe the shared list.
File Description
tests/​e2e-cucumber/​tests/​e2e/​dash_steps.rs Updates a doc comment only; step behavior is unchanged.
docs/​architecture.md Documents the shared menu definition and its consumers.
crates/​rocm-dash-tui/​src/​ui/​menu.rs Derives rows and height from the list; adds rendering tests.
crates/​rocm-dash-tui/​src/​app/​types.rs Defines MenuItem, its labels, and the ordered menu list.
crates/​rocm-dash-tui/​src/​app/​mod.rs Re-exports MenuItem alongside MENU_ITEMS.
crates/​rocm-dash-tui/​src/​app/​actions.rs Uses the list for navigation and activation; adds behavior tests.

Review effort: Balanced

@jussielo-amd
jussielo-amd marked this pull request as ready for review November 5, 2026 13:53
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 5, 2026 13:53

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. The refactor is behaviour-neutral, and the wrap bound, popup height, drawn rows and activation all now derive from the single MENU_ITEMS list. The architecture doc is updated, and the existing dash-14/dash-34 scenarios are cited as the covering behaviour.

None of the inline notes below block the merge:

  • an out-of-range selection currently maps to Quit;
  • the new tests hardcode popup geometry and render twice;
  • one test compares labels against the same label() source, so it can't fail on a wrong label.

Could you confirm you broke the list (e.g. dropped a row from MENU_ITEMS) and saw the new tests go red? The PR body doesn't say. This is a diff-only read. CI should be green before merge: the Strix Halo nightly/release E2E lane was failing when I looked, and MI300X/W7900 were still pending.

Comment thread crates/rocm-dash-tui/src/app/actions.rs Outdated
// A selection past the list (never set by `OpenMenu` or
// `MenuMove`, which keep it in range) still quits, as it did
// when this arm was the index fallback.
Some(MenuItem::Quit) | None => return request_quit(state),

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An out-of-range menu_sel falls into the destructive Quit arm. Preserving the old _ behaviour is fine, but since the state is unreachable by construction, a debug_assert! or a no-op for None would be safer.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in c509cea: the None arm no longer quits; an out-of-range menu_sel is now a no-op that leaves the menu open, with a short comment. It is a deliberate tightening of a state that is unreachable by construction (the commit message says so), and the test is now esc_menu_selection_past_the_last_row_does_nothing, which also asserts the menu stays open. Putting the Quit arm back turns it red.

let theme = Theme::from_name("default-dark");
let area = Rect::new(0, 0, 120, 30);
let mut term = Terminal::new(TestBackend::new(120, 30)).unwrap();
term.draw(|f| super::draw_menu(f, area, 1, &theme)).unwrap();

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

draw_menu is rendered twice in this test (term.draw and then rows). Rendering once and deriving the row text from the same buffer would be simpler.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The test now renders once and builds the row text from that same buffer (6e52003).

Comment thread crates/rocm-dash-tui/src/ui/menu.rs Outdated
};
// The box is 60 wide on a 120-column screen, so its left border is at
// x=30; the cursor column is 7 cells right of it and the label 2 more.
let (cursor_x, label_x) = (37u16, 39u16);

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hardcoded x=37/39 bakes in the popup width (60 on 120 cols), so an unrelated popup sizing change would break this. Deriving it from centered_rect or the frame's left border would be sturdier.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The hardcoded x values are gone: the test finds the box's left border on the Help row and takes the cursor and label columns relative to it (6e52003). Changing the popup width from 60 to 44 leaves all nine menu tests green, while shifting the item column still turns the fixed-column test red.

.iter()
.map(|(_, t)| t.trim_start_matches("▸ "))
.collect();
let listed: Vec<&str> = MENU_ITEMS.iter().map(|i| i.label()).collect();

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both sides go through label(), so a wrong label can't fail this test; it only proves row count and order. Fine as is, as long as the other tests cover the wording.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added a literal Options, Help, Quit assertion next to the one that compares against label() (1be71db); changing the Help label to "Halp" fails the new assertion while the old label() comparison still passes.

An out-of-range `menu_sel` used to share the Quit arm of the Esc menu's
activation match, so it would request a quit. Nothing can set it out of
range (`OpenMenu` resets it and `MenuMove` wraps it), so no user-visible
behaviour changes. This deliberately tightens that unreachable state: the
lookup miss now does nothing and leaves the menu open instead of taking
the destructive path. The test is renamed to match and also asserts the
menu stays open.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…he border

The fixed-column test rendered draw_menu twice, once for the buffer and once
for the row text, and hardcoded the cursor and label columns as absolute
x=37/39, which baked in the popup's width. It now renders once, builds the
row text from that same buffer, and finds the box's left border on the Help
row so the columns are taken relative to it. Changing the popup's width no
longer breaks the test; shifting the item column inside the box still does.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
esc_menu_draws_the_rows_of_the_list_the_selection_walks compares the drawn
rows with MenuItem::label(), so a wrong label appeared on both sides and
could not fail it. Add a literal Options, Help, Quit assertion alongside.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd

Copy link
Copy Markdown
Collaborator Author

Thanks for the approval. Pushed c509cea, 6e52003 and 1be71db for your four inline notes (see the replies on each). On your question whether I broke the list and saw the tests go red: yes, and the PR body's "Mutation proof" section lists it. Against the first commit, adding a fourth label to the draw array only, setting MENU_ITEMS to 4 only and setting MENU_ITEM_COUNT to 4 only each turn tests red; against the final code, dropping Help from MENU_ITEMS fails six tests and a duplicate fourth entry fails four. For the follow-up changes: putting the old Quit arm back, shifting the item column by one and renaming the Help label each fail the test that targets them, and I restored every edit afterwards. cargo test -p rocm-dash-tui passes (1002 unit tests), clippy and fmt are clean. The Strix Halo lane you saw red is the known serve-40 xfail issue (#898).

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 5, 2026
Merged via the queue into main with commit 78e77ff Nov 5, 2026
32 of 33 checks passed
@jussielo-amd
jussielo-amd deleted the refactor-dash-tui-single-menu-item-list branch November 5, 2026 19:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants